refactor(cli): parse JS command arguments with clap - #2523

Move argument parsing for the staged, config, hooks, migrate, and create commands from JavaScript to Rust. Each NAPI parser uses clap for strict validation and returns a typed result to JavaScript.

Call graph

process.argv
    |
    v
local Node.js CLI
packages/cli/src/bin.ts
    |
    | raw arguments for one JavaScript command
    v
NAPI parser function
packages/cli/binding/src/js_command_args/
    |
    v
clap command grammar
    |
    +-- checks aliases and option boundaries
    +-- converts values
    +-- checks explicit negation
    +-- rejects unknown options
    +-- rejects invalid positional arguments
    |
    v
validated Rust arguments
    |
    v
typed NAPI parse outcome
    |
    v
JavaScript command operations

JavaScript sends raw arguments to one NAPI parser. JavaScript does not parse the returned values again.

The Rust parsers print command help through the shared vp_cli_help formatter. The global and local CLI paths use the same help format. The create parser keeps all template arguments after the separator in their original order.

This change removes duplicate JavaScript option data and the direct mri dependency. The RFC defines the parser rules, help synchronization, NAPI result types, and command ownership.

Compatibility

Argument parsing is now strict. The CLI rejects unknown options and extra positional arguments. It rejects unsupported negative string options and repeated scalar options.

The staged command rejects invalid concurrency values. It also rejects empty --cwd, --diff, and --diff-filter values before JavaScript runs.

The create command rejects --all and invalid package-manager values. These inputs could pass through mri or fail later in JavaScript.

Performance

The benchmark compares the base commit 45acff9b4 with this branch. It ran on macOS ARM64 with Node.js 22.22.0.

Each CLI result used 25 to 30 alternating paired runs after four warm-up pairs. A negative change is faster.

The parser-only test used vp staged --allow-empty --concurrent=2 --diff-filter ACMR --no-stash.

The clap/NAPI parser is 5.3 times slower in isolation. This adds about 5 µs to a CLI process that takes 130 to 155 ms.

The CLI calls the parser one time. The complete CLI path has no measurable regression. Help is 1% to 4% faster.

vp config --hooks-dir is not a parser-only comparison. The base command starts hooks validation. The PR rejects the missing value first.

Unknown-option timings are not comparable. The base parser can accept an unknown option and start command work. The PR rejects it during parsing.